Add phase labels and structured fields to config-load observability (#304) by leynos · Pull Request #380 · leynos/netsuke

leynos · 2026-06-13T14:44:03Z

Summary

Closes #304

Extends the #303 config-load instrumentation with per-phase metric labels and structured error-log fields, the additional observability the review audit identified.

Stacked on #379 (#303); retargets to main automatically once #379 merges.

Changes

src/main.rs:
- record_config_load_phase records the diag_mode and merge phases separately, adding a phase label to netsuke_config_load_total (with outcome) and netsuke_config_load_duration_seconds.
- handle_config_load_error annotates the configuration load failed event with operation = "config_merge" and an error_category (parse/io/validation/aggregate/other) derived from the OrthoError variant via the new const fn error_category.
docs/developers-guide.md: per-phase label documentation plus a new Structured log fields subsection documenting the operation/error_category/error contract and the JSON-mode exception.

Testing

Unit tests assert the phase/outcome labels on the counter and histogram and the error_category classification for representative OrthoError variants.

Validation

make check-fmt / make markdownlint / make lint / make test — pass (37 suites)

🤖 Generated with Claude Code

Summary by Sourcery

Add per-phase observability to configuration loading and enrich error logging for config-load failures.

New Features:

Expose configuration-load metrics per phase with phase and outcome labels on existing counter and duration histogram.
Emit structured error logs for configuration-load failures including operation name and coarse error category.

Enhancements:

Refine configuration resolution flow to record separate diagnostic-mode and merge phases with fixed-label values for metrics.
Introduce a helper to classify configuration-load errors into bounded categories for easier operational filtering.

Documentation:

Document per-phase configuration-load metrics and their labels in the developer guide.
Describe the structured log fields emitted on configuration-load failures and clarify their applicability to human-output vs JSON modes.

Tests:

Extend metrics tests to cover phase and outcome labels on config-load metrics and add tests for error category classification.

…304) Extend the config-load instrumentation from #303 so operators can attribute failures and latency to a specific startup phase and a coarse error cause. Metrics: `record_config_load_phase` now records the `diag_mode` and `merge` phases separately, adding a `phase` label to both `netsuke_config_load_total` (alongside `outcome`) and `netsuke_config_load_duration_seconds`. Diagnostic-mode resolution is infallible at the call boundary, so its phase is always `outcome=success`. Structured log fields: `handle_config_load_error` now annotates the `configuration load failed` event with `operation = "config_merge"` and an `error_category` derived from the `OrthoError` variant (`parse`/`io`/`validation`/`aggregate`/`other`). Document the per-phase labels, the structured-log-field contract, and the `error_category` mapping in `docs/developers-guide.md`. Add unit tests for the phase/outcome labels and the error classification.

coderabbitai · 2026-06-13T14:44:10Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 39e6d12b-8c89-457f-88de-b903fff3348c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch issue-304-config-load-observability

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

sourcery-ai · 2026-06-13T14:44:22Z

Reviewer's Guide

Adds per-phase metrics labeling and structured error logging for configuration loading, splitting diagnostic-mode and merge phases and documenting the new observability contract.

Sequence diagram for per-phase config-load metrics

sequenceDiagram
    participant Main
    participant resolve_configuration
    participant cli_resolve_merged_diag_json as cli::resolve_merged_diag_json
    participant cli_merge_with_config as cli::merge_with_config
    participant record_config_load_phase

    Main->>resolve_configuration: resolve_configuration(parsed_cli, matches)
    activate resolve_configuration

    resolve_configuration->>cli_resolve_merged_diag_json: resolve_merged_diag_json(parsed_cli, matches)
    cli_resolve_merged_diag_json-->>resolve_configuration: mode_json_enabled

    resolve_configuration->>record_config_load_phase: record_config_load_phase(PHASE_DIAG_MODE, diag_elapsed, true)

    resolve_configuration->>cli_merge_with_config: merge_with_config(parsed_cli, matches)
    cli_merge_with_config-->>resolve_configuration: merged_result

    resolve_configuration->>record_config_load_phase: record_config_load_phase(PHASE_MERGE, merge_elapsed, merged_result.is_ok())
    resolve_configuration-->>Main: (mode, merged_result)
    deactivate resolve_configuration

Sequence diagram for structured error logging on config-load failure

sequenceDiagram
    participant Main
    participant handle_config_load_error
    participant error_category
    participant tracing_error as tracing::error

    Main->>handle_config_load_error: handle_config_load_error(err, mode)
    activate handle_config_load_error

    alt mode.is_json()
        handle_config_load_error-->>Main: diagnostic_json::emit_or_fallback(...)
    else human_output_mode
        handle_config_load_error->>error_category: error_category(err)
        error_category-->>handle_config_load_error: category
        handle_config_load_error->>tracing_error: error!(error=%err, operation="config_merge", error_category=category, ...)
        tracing_error-->>handle_config_load_error: event_recorded
        handle_config_load_error-->>Main: ExitCode::FAILURE
    end

    deactivate handle_config_load_error

File-Level Changes

Change	Details	Files
Split configuration-load observability into per-phase metrics with phase labels and updated tests.	Refactored configuration resolution to measure diagnostic-mode and merge phases separately with distinct start times. Replaced record_config_load_metrics with record_config_load_phase, adding a phase label to both the duration histogram and outcome counter. Introduced PHASE_DIAG_MODE and PHASE_MERGE constants and used them when recording metrics. Updated unit tests to assert presence of phase and outcome labels on the counter and histogram and adjusted test names accordingly, adding a small label-search helper.	`src/main.rs`
Add structured error logging for configuration-load failures with coarse error categorization.	Introduced const fn error_category that maps OrthoError variants into coarse categories (parse, io, validation, aggregate, other). Extended handle_config_load_error to emit structured tracing::error! fields: error, operation="config_merge", and error_category derived from the OrthoError. Added a dedicated test to verify error_category classification for representative OrthoError variants.	`src/main.rs`
Update developer documentation to describe new per-phase metrics and structured log fields for config-load failures.	Rewrote metrics documentation to describe record_config_load_phase semantics, including phase/outcome label combinations and recommended usage for failure rate calculations. Clarified duration histogram semantics as per-phase samples and reaffirmed bucket recommendations and cardinality constraints. Added a new "Structured log fields" subsection documenting operation/error_category/error fields and the JSON-mode exception for human vs machine-readable output.	`docs/developers-guide.md`

Possibly linked issues

Improve observability of config-load error paths: structured log fields, metrics by phase #304: PR implements structured log fields, per-phase metrics, histograms, and documentation exactly as requested in issue Improve observability of config-load error paths: structured log fields, metrics by phase #304.

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

codescene-delta-analysis Bot approved these changes Jun 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add phase labels and structured fields to config-load observability (#304)#380

Add phase labels and structured fields to config-load observability (#304)#380
leynos wants to merge 1 commit into
issue-303-config-load-metricsfrom
issue-304-config-load-observability

leynos commented Jun 13, 2026 •

edited by sourcery-ai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 13, 2026

Review skipped

Uh oh!

sourcery-ai Bot commented Jun 13, 2026

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

leynos commented Jun 13, 2026 • edited by sourcery-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Testing

Validation

Summary by Sourcery

Uh oh!

coderabbitai Bot commented Jun 13, 2026

Review skipped

Uh oh!

sourcery-ai Bot commented Jun 13, 2026

Reviewer's Guide

Sequence diagram for per-phase config-load metrics

Sequence diagram for structured error logging on config-load failure

File-Level Changes

Possibly linked issues

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

leynos commented Jun 13, 2026 •

edited by sourcery-ai Bot

Loading